Working With Track References1

Track references allow you to relate tracks to one another. For example, this can be useful to identify the text track that contains the subtitles for a movie's audio track, and relating the text track to a particular audio track. See "Track References," in this chapter, for more information about track references.

The AddTrackReference function allows you to relate one track to another. The DeleteTrackReference function removes that relationship. The SetTrackReference and GetTrackReference functions allow you to modify an existing track reference so that it identifies a different track. The GetNextTrackReferenceType and GetTrackReferenceCount functions allow you to scan all of a track's track references.

AddTrackReference

The AddTrackReference function allows you to add a new track reference to a track.



 
pascal OSErr AddTrackReference (Track theTrack, Track refTrack, OSType refType, 

                     long *addedIndex);

theTrack: Identifies the track for this operation. Your application obtains this track identifier from such Movie Toolbox functions as NewMovieTrack and GetMovieTrack .
refTrack: Specifies the track to be identified in the track reference.
refType: Specifies the type of reference.
addedIndex: Contains a pointer to a long. The Movie Toolbox returns the index value assigned to the new track reference. If you do not want this information, set this parameter to nil .

RESULT CODES



 

invalidTrack

-2009

This track is corrupted or invalid

Memory Manager errors

DeleteTrackReference

The DeleteTrackReference function allows you to remove a track reference from a track.



 
pascal OSErr DeleteTrackReference (Track theTrack, OSType refType, long index);

theTrack: Identifies the track for this operation. Your application obtains this track identifier from such Movie Toolbox functions as NewMovieTrack and GetMovieTrack .
refType: Specifies the type of reference.
index: Specifies the index value of the reference to be deleted. You obtain this index value when you create the track reference.

Description

This function deletes a track reference from a track. If there are additional track references with higher index values, the Movie Toolbox automatically renumbers those references, decrementing their index values by 1.

RESULT CODES

`paramErr`	-50	Invalid parameter specified
`invalidTrack`	-2009	This track is corrupted or invalid

Memory Manager errors

SetTrackReference

The SetTrackReference function allows you to modify an existing track reference. You may change the track reference so that it identifies a different track in the movie.



 
extern pascal OSErr SetTrackReference (Track theTrack, Track refTrack, OSType refType, 

                     long index);

theTrack: Identifies the track for this operation. Your application obtains this track identifier from such Movie Toolbox functions as NewMovieTrack and GetMovieTrack .
refTrack: Specifies the track to be identified in the track reference. The Movie Toolbox uses this information to update the existing track reference.
refType: Specifies the type of reference.
index: Specifies the index value of the reference to be changed. You obtain this index value when you create the track reference.

RESULT CODES

`paramErr`	-50	Invalid parameter specified
`invalidTrack`	-2009	This track is corrupted or invalid

GetTrackReference

The GetTrackReference function allows you to retrieve the track identifier contained in an existing track reference.



 
pascal Track GetTrackReference (Track theTrack, OSType refType, long index);

theTrack: Identifies the track for this operation. Your application obtains this track identifier from such Movie Toolbox functions as NewMovieTrack and GetMovieTrack .
refType: Specifies the type of reference.
index: Specifies the index value of the reference found. You obtain this index value when you create the track reference.
function result: Returns the track identifier contained in the specified track reference.

Description

This function returns the track identifier that is contained in the specified track reference. If the Movie Toolbox cannot locate the track reference corresponding to your specifications, it returns a value of nil .

GetNextTrackReferenceType

The GetNextTrackReferenceType function allows you to determine all of the track reference types that are defined for a given track.



 
pascal OSType GetNextTrackReferenceType (Track theTrack, OSType refType);

theTrack: Identifies the track for this operation. Your application obtains this track identifier from such Movie Toolbox functions as NewMovieTrack and GetMovieTrack .
refType: Specifies the type of reference. Set this parameter to 0 to retrieve the first track reference type. On subsequent requests, use the previous value returned by this function.
function result: Returns an operating-system data type.

Description

This function returns an operating-system data type containing the next track reference type value defined for the track. There is no implied ordering of the returned values. When you reach the end of the track's reference types, this function sets the returned value to 0. You can use this value to stop your scanning loop.

GetTrackReferenceCount

The GetTrackReferenceCount function allows you to determine how many track references of a given type exist for a track.



 
pascal long GetTrackReferenceCount (Track theTrack, OSType refType);

theTrack: Identifies the track for this operation. Your application obtains this track identifier from such Movie Toolbox functions as NewMovieTrack and GetMovieTrack .
refType: Specifies the type of reference. The Movie Toolbox determines the number of track references of this type.
function result: Returns a long integer or 0.

Description

This function returns long integer that contains the number of track references of the specified type in the track. If there are no references of the type you have specified, the function returns a value of 0.